TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/CRS/crs05.d81/evsbasic.arc/EVSKEYWORDS.A-D

Text File | 2009-10-10 | 15KB | 422 lines

EVS Basic 1.00 Keyword Descriptions
(C) 1988  by  Anton Treuenfels

Last Revision:  08/30/88

This document describes the EVS Basic keywords and what they do.  Each
description also includes a few examples of the use of the keyword
(although these examples appear as they would in program mode, all keywords
also function in immediate mode).

Most EVS Basic keywords require one or more parameters.  The type and
number of parameters are indicated between angle brackets after the keyword
itself:  keyword <parameter>.  Many EVS Basic keywords also accept optional
parameters, which are indicated by square brackets surrounding the angle
brackets:  [<optional>].  Ellipses within square brackets mean that the
entire enclosed block of parameters may be repeated as often as desired:
[[<optional>]...].  When an optional parameter of a keyword is used in a
statement there is often also a separator character (usually a comma)
required to distinguish it from any other parameters:  <required> [,
<optional>] or [<optional>,] <required>.

A few keywords have a series of "semi-optional" parameters:  [ <optional>
[, <optional> [, <optional>]]].  Such series usually indicate that at least
one but not necessarily all of the <optional> parameters be present.  With
a series of optional parameters it is possible to "skip over" any the
programmer does not wish to use by just using the separator character to
indicate an unused parameter:  <optional>, , , <optional>.  The separator
character is required between used and unused optional parameters only up
to the last one actually present.  The separator character is not required
or accepted beyond that point.

---------------------------------------

BIN$(<hex$>)

The BIN$() function combines pairs of ASCII Hex characters from <hex$> to
produce an equivalent binary string.  If <hex$> has an odd number of
characters, BIN$() will ignore the last character.

The sixteen ASCII Hex characters are "0" to "9" and "A" to "F".  Each ASCII
Hex character represents half of a binary character, so two are needed for
each character in the finished binary string (thus a character pattern for
IMAGE requires sixteen ASCII Hex characters, and a sprite image requires
126).  The first character of each pair is taken as the "left" or "upper"
half of a binary character, while the second is taken as the "right" or
"lower" half (from a more technical point of view, the first character
represents the "high nybble" and the second character the "low nybble" of
eight-bit bytes).

The binary patterns represented by each ASCII Hex char are listed below:

ASCII Hex      Pattern:

"0"          0  0  0  0
"1"          0  0  0  1
"2"          0  0  1  0
"3"          0  0  1  1
"4"          0  1  0  0
"5"          0  1  0  1
"6"          0  1  1  0






"7"          0  1  1  1
"8"          1  0  0  0
"9"          1  0  0  1
"A"          1  0  1  0
"B"          1  0  1  1
"C"          1  1  0  0
"D"          1  1  0  1
"E"          1  1  1  0
"F"          1  1  1  1

Examples:

10 A$= BIN$(B$)
20 IMAGE "T", BIN$("3C42A581A599423C"): REM HAPPY FACE
30 FOR I=0 TO 15: READ A$: IMAGE I, BIN$(A$): NEXT

---------------------------------------

CAT [<pattern$>] [, <dvc#>]

The CAT command is used to display all or part of the directory of a diskette.
The CAT keyword by itself lists the entire directory of the diskette in the
default disk device (normally device 8) to the screen.

<Pattern$> can be used to list only filenames containing that pattern.  The
wildcard characters "?" and "*" can be used in the pattern and have their normal
meaning.

<Dvc#> may be used to select any particular disk device, including the default
device.  A directory is normally taken from drive 0, but if the device is dual
drive either drive may be specified by using the first two characters of
<pattern$>:  "0:" (for drive 0) or "1:" (for drive 1).

Examples:

10 CAT
20 CAT "TEST"
30 CAT , 8
40 CAT "1:", 9

---------------------------------------

CUR(<nexp>)

This function returns a value indicating the cursor X- or Y-position or the
value "under" the cursor.  The sign of <nexp> determines the type of value
returned by CUR().  If zero, CUR() returns the physical (not logical) X-position
of the cursor.  If positive, CUR() returns the physical (not logical) Y-position
of the cursor.  If negative, CUR() "looks under" the cursor and returns either
the screen code of the character (if in a text mode) or the pen value of the
pixel (if in a bitmap mode) found there.

Examples:

10 X = CUR(0): Y = CUR(1)
20 LINE CUR(0) + 5, CUR(1) - 10
30 IF CUR(-1) = 3 THEN EXIT

---------------------------------------







DIR [<pattern$>] [, <dvc#>]

The DIR command is used to display all or part of the directory of a
diskette.  The DIR keyword by itself lists the entire directory of the
diskette in the default disk device (normally device 8) to the screen.

<Pattern$> can be used to list only filenames which begin with the pattern.
The wildcard characters "?" and "*" can be used in the pattern and have
their normal meaning.  Alternatively, filetypes instead of filenames can be
matched using a "*=<filetype>" pattern.

<Dvc#> may be used to select any particular disk device, including the
default device.  A directory is normally taken from drive 0, but if the
device is dual drive either drive may be specified by using the first two
characters of <pattern$>:  "0:" (for drive 0) or "1:" (for drive 1).

Examples:

10 DIR
20 DIR "B?N?N?"
30 DIR , 8
40 DIR "*=PRG"

---------------------------------------

DO [WHILE/UNTIL <exp>]

The DO statement marks the start of a DO/LOOP repeat structure.  The DO
statement is physically the first statement of the loop.  Every DO must
have one, and only one, matching LOOP statement.

The basic DO/LOOP structure is unconditional, and all program statements
between a DO statement and a LOOP statement will repeatedly execute in
order forever (or until the program is halted by the STOP key).  This is
useful in some cases, but more often a program exits from a DO/LOOP when
some condition is fulfilled.

A DO statement may optionally be followed by either the WHILE or UNTIL
conditional statements.  A WHILE conditional will continue repeating the
loop only so long as <exp> is true.  An UNTIL conditional will continue
repeating the loop only so long as <exp> is false.  Note that since either
condition is evaluated before the first program statement contained within
the loop is executed, it is possible to create a loop which may never
actually be executed.

When a DO/LOOP is terminated by WHILE, UNTIL, or EXIT, normal program
execution continues starting with the next statement after the LOOP
matching the DO.

DO/LOOPs may be nested within each other or within FOR/NEXT loops, and
FOR/NEXT loops may be nested within DO/LOOPs.  The total number of active
nested loops of both kinds should not exceed nine.

Examples:

10 DO: PRINT "HELLO": LOOP
20 DO UNTIL A<0: READ A: PRINT A: LOOP

---------------------------------------







DOS <command$> [, <dvc#>]

The DOS statement sends a <command$> to the command channel of a disk
device.  The <command$> may be any legal disk command that in V2 Basic
would normally be PRINTed to channel 15 (the disk command channel).  The
most common uses for this statement are initializing a drive, formatting a
diskette, and scratching unneeded files.  Less often used commands include
validating a disk, renaming a file, copying a file, and direct disk access.
See Chapter 4 of the "1541 User's Manual" for details of the various disk
commands.

<Dvc#> may be used to select any particular disk device, including the
default device.

Examples:

10 DOS "I0"
20 DOS "S0:TEST*"
30 DOS "N0:MYDISK,MD",8

---------------------------------------

DRAW <shape$> [[;][<shape$>]...]

The DRAW statement "draws" a figure defined by a <shape$> on a bitmap
screen.  In general a <shape$> can be drawn much more quickly and is more
easily relocated about the screen than an equivalent shape drawn with LINE
statements.  On the other hand, it is usually not as easy to create a
<shape$> as it is to simply list points to be connected by LINE.

DRAW interprets a <shape$> as a coded list of graphics commands.  Commands
are included to move the cursor, plot points, draw lines, paint an area,
change the pen, and expand or contract the shape in the X- or Y-directions.
Each command is two, four, or six characters long and is of the general
form:

CHR$(128) + CHR$(command) [+ param$]

By default DRAW draws a <shape$> at the current cursor position using the
current pen in the current size.  After a <shape$> is drawn the cursor,
pen, and size are left as last set by the <shape$> definition.  The first
<shape$> definition can optionally be followed by as many more <shape$>
definitions as will fit on a program line.

The 17 commands recognized by DRAW are described below.  Unrecognized
commands generate an "?UNKNOWN CHAR" error.

The following six commands require coordinate parameters:

Move cursor:   "m"+X$+Y$ or "M"+X$+Y$
Plot point:    "d"+X$+Y$ or "D"+X$+Y$
Draw line:     "l"+X$+Y$ or "L"+X$+Y$

DRAW interprets the coordinates specified in the above commands as being
relative to the current cursor position rather than absolute, so they may
be either positive or negative values.  Also, DRAW uses only the physical
coordinate system of the bitmap screen (0,0 is the upper left hand corner
and 319,199 the lower right), so that positive X is right, negative X is
left, positive Y is down, and negative Y is up.  The use of relative
coordinates enables a shape to be drawn anywhere on the screen.







The difference between the lowercase and uppercase forms of each command is
the allowed range of coordinates, and thus the overall number of characters
needed to specify that range.  The lowercase forms allow X and Y values in
the range -127 to +127 and require two characters, while the uppercase
forms may range from -319 to +319 for X and -199 to +199 for Y and require
four characters.  Note that since the cursor is not allowed to move outside
the physical screen range the maximum range values may not always be
available.

The parameter characters needed for the lowercase forms of the above
commands can be created in several steps.  First, the numeric value of each
character is calculated using the following function:

DEF FN LC(C)= C - 256 * (C<0)

This function is valid for the range -127 to +127.  Given X and Y in this
range, the two characters necessary to the lowercase form can be created:

X$ = CHR$(FN RP(X))
Y$ = CHR$(FN RP(Y))

A similar method can be employed for the uppercase forms of the commands.
First, functions to create the numeric value:

DEF FN UL(C)= (C - 65536 * (C<0)) AND 255
DEF FN UH(C)= (C - 65536 * (C<0)) / 256

These functions are valid for the range -32767 to +32767, which is far more
than needed.  The characters themselves can be formed like this:

X$ = CHR$(FN UL(X)) + CHR$(FN UH(X))
Y$ = CHR$(FN UL(Y)) + CHR$(FN UH(Y))

A complete move, point, or line command thus looks like:

CHR$(128) + command$ + X$ + Y$

where <command$> is "m", "M", "d", "D", "l" or "L".

The only other DRAW command that requires parameters is the paint command:

Paint area:   "p"+T$+B$ or "P"+T$+B$

The lowercase paint is a threshold paint in the range 0-63 or 128-191, and
T$=CHR$(threshold).

The uppercase paint is a pattern paint, and T$ represents the character to
use as the pattern.

In either case B$ is the boundary of the filled area.  The boundary value
can be a particular pixel value in the range 0-3 or it may be 255 to stop
the fill at any non-zero pixel, and B$=CHR$(boundary).

A complete paint command thus looks like:

CHR$(128) + command$ + T$ + B$

where <command$> is "p" or "P".







The following DRAW commands change the current pen:

Set pen 0:    CTRL-Z or CHR$(26)
Set pen 1:    CTRL-X or CHR$(24)
Set pen 2:     CTRL-C or CHR$(3)
Set pen 3:    CTRL-V or CHR$(22)
Set pen 4:     CTRL-B or CHR$(2)

The following DRAW commands change the current size of the shape:

Normal X-size:   F1 or CHR$(133)
Double X-size:   F2 or CHR$(137)
Normal Y-size:   F3 or CHR$(134)
Double Y-size:   F4 or CHR$(138)

Both of the above sets of commands require no parameters and have the form:

CHR$(128) + command$

where <command$> is one of the CHR$() values shown.

All DRAW commands are required to begin with CHR$(128) followed by a legal
command character.  There is one exception to this rule:  a command which
does not start with CHR$(128) is assumed to be an "l" command, that is, a
line command in the range -127 to +127.  In this case the "l" character
does not have to be specified either, so only the two coordinate parameter
characters are needed.

Examples:

10 DRAW A$
20 DRAW A$(I)
30 DRAW CHR$(128)+CHR$(137);A$

---------------------------------------

DS and DS$

DS and DS$ are pseudo-variables relating to the error status of a disk
device.  They may be used in any way normal variables are except that they
cannot be assigned values.  Instead, each time DS$ is referenced it will
return the current status message of the most recently used disk device.
DS always returns the number of the last message retrieved by DS$.

A disk status message has the general form "error number, error message,
track, sector".  After a successfully executed disk command DS$ will return
the string "00,OK,00,00" and DS will have the value 0.  See Appendix B of
the "1541 User's Manual" for complete descriptions of other error messages
and their causes.

Note that the value of DS never changes except when DS$ changes.  This can
be useful if an error occurs when a disk drive attempts to execute a
command (the activity light begins to blink).  Only the very next reference
to DS$ will return the correct error message.  After that the error is
"cleared" (the activity light stops blinking) and any new reference to DS$
will return the "OK" message.  DS, on the other hand, will return the
number associated with the now-cleared error until the next reference to
DS$.

Examples:







10 PRINT "DISK STATUS "; DS$
20 A$ = DS$
30 IF DS > 0 AND DS <> 50 THEN 9000

---------------------------------------

DVC <nexp>

The DVC statement sets the default mass-storage device number.  If a
command requires a device number and none is explicitly specified, then the
command is directed to the default device.  The default device can be the
tape drive or any of the disk drives.  EVS Basic uses device 8 (the first
disk drive) as the default device until changed by DVC.

LOAD, SAVE, and VERIFY do not care what the default device is, but CAT,
DIR, and DOS will signal an "?ILLEGAL DEVICE ERROR" if they are directed to
the tape drive.

Examples:

10 DVC 1
20 DVC 10
20 DVC IO(A)